Check out the CompuServe MACCOMM forum, LIB 14 or http://www.logic.be for more recent versions.
This software is freeware. Please do not distribute it without this Readme file. You may customize this software for your own purposes, but please don't redistribute customized versions: only unmodified versions can be distributed.
This software is distributed 'as is': no warranties are made, either expressed or implied.
Thanks to Paul Van Cotthem of Apple Computer Belgium: many of the features of this program were suggested by him.
Internet address: vancotthem.p@applelink.apple.com
If you are updating an older version: the update history is appended at the end of this document.
WHAT DOES IT DO?
TextToHTML quickly converts text or RTF files dropped onto its icon into HTML format. When converting multiple text, RTF or HTML files at once, it also creates an HTML index file with links to those files, complete with graphical bullets if necessary. It can also automatically link images. With TextToHTML you can set up a basic WWW structure in 15 minutes, starting from scratch.
(RTF = Rich Text Format, used by several word processors; HTML = Hyper Text Markup Language, used for formatting documents on the World Wide Web).
• The first 'real' text line it finds in an original text or RTF file is interpreted to be the window title and it is also tagged as an <H1> header. The rest of the file is considered to be body text.
• For reference purposes, the filename of the original file is added at the end of the resulting HTML file.
• Single carriage returns or line feeds are converted to the <BR> tag, multiple sequential carriage returns are collapsed into a <P> tag.
• Special and reserved characters are converted according to the list of ISO Latin-1 character entities. Mac characters without ISO Latin-1 counterpart are converted to character sequences with some visual similarity.
(For more information on this, check out this URL: http://www.utirc.utoronto.ca/HTMLdocs/NewHTML/entities.html).
• The creator of the converted HTML files is set to MOSS (Netscape). You can change this (see below).
• If there are GIF or JPEG files present for use as a logo, bullets, or illustrations, they can be linked in automatically.
HOW TO USE IT?
There are three ways to use it:
1) If you drop a single file onto the TextToHTML application icon, it gets converted into HTML format and it is saved in the same folder as the original file. The name of the resulting HTML file will be a derivative of the original file's name, with ".html" appended.
Tip: if you have no permission to write in this folder, TextToHTML will just beep, and do nothing. This can occur on CD-ROMS and on file servers. First copy the file to a location where you do have write access.
Tip: if you want to run the conversion again on the same file, you don't have to trash the previous .html file first, because it will be overwritten.
Tip: you can use the resulting .html file as a base to start with, and add graphics and extra links manually with an HTML editor.
Tip: if your Macintosh desktop is corrupt, TextToHTML will not let you drop anything. In that case, rebuild your desktop first (hold Command-Option during startup).
2) If you drop multiple files onto the TextToHTML application icon, they all get converted into HTML format, and an additional index file with hot links to the other files is created. The converted files are stored in the same folder as the index file. Except for the index file, the names of the HTML files are of the form "X####_<name>.html", where #### is a sequential number, and <name> is a derivative of the original file name. Start browsing from the index file. Each "X" file contains a backlink to the main index file.
Tip: If you hold the option key while dropping multiple files onto TextToHTML, the files are processed one by one without creating an index file.
3) If you drop a folder onto the TextToHTML application, it converts all the files in that folder and its sub-folders. It creates a main index file, which is the root of a tree-structure that mimics the structure of the folders. The HTML files are all stored in the same folder as the main index file. Each "X" file contains backlinks to the main index file and to the file one level up in the tree structure.
Tip: if TextToHTML finds .html files in the original folder structure, they are just copied without changes, and linked into the menu structure. Their content is not changed or updated in any way - so check their links afterwards!
Tip: you can use this last feature to insert 'gateway'-documents to distant pages in your menu structure.
Tip: don't be alarmed if a certain sub-folder does not appear in the index tree: if there are no convertible documents in a folder or one of it's subfolders, it is not added to the index tree.
ADDING GRAPHICS
If you have illustrations that you want to include, you should first put them in the destination folder, before using TextToHTML. For every original TEXT or RTF file called <file>, there will be an auto-inclusion of one or more of the files called:
<file>.jpg
<file>.gif
<file>_t.jpg
<file>_t.gif
<file>_m.jpg
<file>_m.gif
<file>_b.jpg
<file>_b.gif
For example: if you have a file called Kris somewhere in the source folder, and you provide a file Kris.gif in the destination folder before the conversion, the image Kris.gif will be auto-inserted just after the title in the HTML file that results from converting the file Kris.
<file>.gif and/or <file>.jpg is included just after the title in the converted file.
<file>_t.gif and/or <file>_t.jpg (t stands for 'top') is included before the converted file, just after the optional logo.
<file>_m.gif and/or <file>_m.jpg (m stands for 'middle') is included after the title in the converted file, and eventually after <file>.gif and <file>.jpg if one of these is present.
<file>_b.gif and/or <file>_b.jpg (b stands for bottom) is included after the body of the converted file.
Try the included example - it will make things easier to understand!
ADDING LOGO AND BULLETS
If you want to insert your logo or some graphical bullets in all HTML files, you should provide one or more of the following four files in the destination folder before the conversion:
logo.gif or logo.jpg is inserted at the top at every converted file. Put your company logo in this file.
bullet.gif or bullet.jpg is prefixed to every link to a converted document.
submenu.gif or submenu.jpg is prefixed to every link to a submenu (corresponds to a subfolder).
index.gif or index.jpg is prefixed to every link back to the previous index file.
topindex.gif or topindex.jpg is prefixed to every link back to the top index file.
Check the included example. In the example, topindex.gif and index.gif look equal because of lack of inspiration on my side...
YOU SHOULD KNOW THAT...
TextToHTML has very little error handling: it just beeps and quits. Possible causes: application size to small, no write access, or just plain bugs. Let me know if you encounter them!
TextToHTML currently ignores character formatting in text files. For example if you would convert this Readme file (which was created with SimpleText), the bold, italic and underline styles are not converted into HTML tags.
TextToHTML also reads and converts Mac RTF files, but this is still pretty beta: if you encounter problems with a particular RTF file, I would be happy if you sent it to me over e-mail, so I can further debug TextToHTML.
You should be careful not to use names like the ones TextToHTML uses for your own HTML files, to avoid name conflicts.
HOW TO CUSTOMIZE IT ?
If you have ResEdit handy, you can do some customisations.
There are two STR# resources you can change: 20000 and 20001.
• 20000 contains parameters (creator, texts used,...); just open it: I added remarks to make it somewhat self-explanatory.
Tip: if you want to change the creator from Netscape (MOSS) to another application, change string 2.
Tip: if you want the resulting index files sorted by file name, rather than by document title, change string 42 to a 1. Attention: when (and only when) you do this, TextToHTML will strip leading spaces and digits from folder names before using them in an index file. This allows you to customise the order of your documents and subfolders in the Finder by prefixing them with one or more spaces and digits 0-9. Use the 'View by Name' setting to look into the main folder. The leading digits and spaces will not show up in the HTML menus.
• 20001 contains the translation table: there are 255 strings, one for every ASCII character except NUL. If a string is empty, the character is not translated.
Tip: You can insert some extra HTML code in the converted files in different locations: before the header, after the header, at the end of the file, before a hotlink, after a hotlink,....
I used this feature to add:
«10»«17»
<EM>This file was converted with TextToHTML - (c) Logic n.v.</EM>
at the end of every file: if you want to eliminate this, just change or empty STR# 20000 - string 24. Please do not redistribute versions with this string changed! The text «10» is a macro that is replaced by a reference to the image <file>_b.gif and/or <file>_b.jpg if these are present in the destination folder. «17» is a macro that is replaced by a text that mentions the name of the original file if applicable.
MACROS
I do not intend to document these extensively - I implemented them mostly to make life a little easier for myself when customising TextToHTML, and not everything is tested: so no warranties! In short, everything between « and » (ASCII 199 and 200), is interpreted as a macro. Macros are evaluated recursively.
• If this macro string is numeric, it is replaced by the string with the same number from STR# 21000. If this string contains macros, they are also evaluated.
• There are also some symbolic macros:
«IFN» is the name of the original file
«OFN» is the name of the HTML file
«IDX» is the name of the index file one level up
«TIDX» is the name of the top level index file
«PCOUNT» is the number of <P> strings generated up to this point.
«BRCOUNT» is the number of <P> strings generated up to this point.
• Conditional macros:
«?string1:=string2» is a conditional macro that only inserts string2 if string1 is an existing file in the destination folder.
«!string1:=string2» is a conditional macro that only inserts string2 if string1 is not empty
• You can also replace the ':=' by '::'. If you do so, string2 will be put through an extra translation to HTML.
Normally, you cannot insert macros in text documents, because ASCII 199 and ASCII 200 are translated to different characters before macro's are evaluated. If you would like to use macro's in your text documents, you have to empty STR# 20001, string 199 and 200.
UPDATE HISTORY
NEW in 1.2.3
• Strip leading digits and spaces from directory names when ordering by file name.
• Changed default file name to 'index.html' (with lower case i).
NEW in 1.2.2
• Macro-strings implemented (not documented) to make conditional inserts in generated HTML code: depending on the presence or absence of files in the destination folder, extra HTML code is generated.
• Restructured STR# 20000 and 20001 using macro strings.
• Auto-insert of bullets, logo, images,... if they are present and named according to a simple naming convention.
• Changeable sorting criterium for generated menu options
NEW in 1.2.1
• If STR# 20000 - string 8 is emptied, the filename of the original file is NOT appended to the converted document.
NEW in 1.2.0
• Resolved bug in RTF file reader: soft hypens are now interpreted OK.
• Added option-drag feature for multiple files: when holding down option key when dragging multiple documents onto TextToHTML, the files are converted without creating index files.
NEW in 1.1.10
• Added customisable prefixes and suffixes for:
- normal menu hot links (default <B> and </B>)
- hot links to sub menus (default empty)
- hot links to previous level (default empty)
- hotlinks to upper level (default empty)
NEW in 1.1.9
• Added translation for the following characters which are supported by Netscape:
